The complexity of this loop (which should be using ipairs, btw) will grow with the number of notes/squad waypoints that are defined. would it be a good idea to cache them in a nested map structure so you can retrieve a note via safe_index(self.notes_cache, pos.z, pos.y, pos.x)?

I optimized it now in different way - I scan only notes that are visible (and cached before). What do you think?

A mouse-capable way of adding a note is generally expected of current tools. See gui/blueprint for a possible example. You click on a button and then click on the map. while the location is being selected, a marker is rendered under the mouse cursor: https://github.com/DFHack/scripts/blob/master/gui/blueprint.lua#L427

seems very good, but for now we do not have any notes interface where such button can be placed.
Do you think I should replace notes add command by mouse cursor selection?
Or this should stay as it is and the new way should appear after there will be a gui/notes for managing notes?

I think there should be a gui/notes entrypoint, but I also think that this dialog should have a way to create (and switch to editing) an additional note

This would be confusing.

1. You clicked on a note to edit it and in a dialog you have option "New note"? Did you current changes to note saved or not? Do it switch to new note overlay mouse hover mode? etc.

2. You creating a new note, and got to moment when you see this dialog. Then you switch to editing. What this really means? You are forced to select a note on the screen now? Its sounds very confusing.
   If you want to switch to editing - just select a note on the map. You can do this right now, do not need any additional wat to "switch" to it.
   --
   I never met such features in my web/desktop experience. Edit dialog is for editing, new dialog is for creating.

I believe the needs you speak about will be fully solved by gui/notes tool.
I though I can create it later, but maybe it should be done from the begining to avoid the confusion.